/*
 * Copyright (c) 2009. Silenus Consultoria, S.L.
 */
package es.silenus.detecta.dao;

import java.util.Collection;
import java.util.List;
import java.util.Map;


/**
 * Read-only generic DAO interface.
 *
 * @author <a href="mailto:malonso@silenus-consultoria.es">Mariano Alonso</a>
 * @since 22-mar-2009 11:04:04
 */
public interface ReadDAO<T, K> {
	/**
	 * Finds an object by its identifier.
	 *
	 * @param key the key.
	 *
	 * @return the object or null if not found.
	 */
	public T findById(final K key);

	/**
	 * Finds objects by its primary keys.
	 *
	 * @param keys the keys.
	 *
	 * @return the list of objects.
	 */
	public List<T> findByIds(final K[] keys);

	/**
	 * Finds objects by its primary keys.
	 *
	 * @param keys the keys.
	 *
	 * @return the list of objects.
	 */
	public List<T> findByIds(final Collection<K> keys);

	/**
	 * Finds the objects that satisfy a search criteria expressed as an example object bean.
	 *
	 * @param sample the sample object bean.
	 *
	 * @return the results.
	 */
	public List<T> findByExample(final T sample);

	/**
	 * Finds the objects that satisfy a search criteria expressed as an example object bean.
	 *
	 * @param sample the sample object bean.
	 *
	 * @return the results.
	 */
	public List<T> findByExample(final Map<String, Object> sample);

	/**
	 * Finds the objects that satisfy a search criteria expressed as an example object bean and a pagination object
	 * to limit and sort.
	 *
	 * @param sample the sample criteria.
	 * @param start the start index.
	 * @param limit the limit index.
	 * @param sortFields the sort fields.
	 * @param sortDirections the sort directions.
	 *
	 * @return the page.
	 */
	public Page<T> findByExample(final Map<String, Object> sample,
															 int start,
															 int limit,
															 final String[] sortFields,
															 final String[] sortDirections);

	/**
	 * Builds a page.
	 *
	 * @return a page.
	 */
	public Page<T> buildPage();

	/**
	 * Finds the unique instance that satisfies a search criteria expressed as an example object bean.
	 *
	 * @param sample the sample object bean.
	 *
	 * @return the unique result.
	 */
	public T findUniqueByExample(final T sample);

	/**
	 * Finds the unique instance that satisfies a search criteria expressed as an example object bean.
	 *
	 * @param sample the sample object bean.
	 *
	 * @return the unique result.
	 */
	public T findUniqueByExample(final Map<String, Object> sample);

	/**
	 * Loads every single instance of a persistent class.
	 *
	 * @return list of instances.
	 */
	public List<T> findAll();

	/**
	 * Clears the cache.
	 */
	public void clearCache();
}
